package net.cassite.daf4j;

import java.util.List;
import java.util.Map;

/**
 * Pure.Data操作的实际执行接口.<br>
 * 从以下类的文档中查看调用信息
 *
 * @author wkgcass
 * @see Query
 * @see PreResult
 */
public interface DataAccess {
        /**
         * 根据标识符进行查询
         *
         * @param entityClass 实体类
         * @param pkValue     主键值
         * @param <En>        实体类型
         * @return 查询结果, 实体
         */
        <En> En find(Class<En> entityClass, Object pkValue);

        /**
         * 执行查询,注入实体并返回结果List
         *
         * @param <En>        实体类型
         * @param entity      要查询的实体
         * @param whereClause 查询条件
         * @param parameter   查询参数(可以为空)
         * @return 查询的实体结果List
         */
        <En> List<En> list(En entity, Where whereClause, QueryParameter parameter);

        /**
         * 执行查询,生成List&lt;Map&lt;字段名,对象&gt;&gt;形式的结果.
         *
         * @param entity      要查询的实体
         * @param whereClause 查询条件
         * @param parameter   查询参数(可以为空,若为空则查询所有非聚合类型的字段)
         * @return 查询的Projection结果
         */
        List<Map<String, Object>> projection(Object entity, Where whereClause, QueryParameterWithFocus parameter);

        /**
         * 执行更新
         *
         * @param entity      目标实体
         * @param whereClause 更新条件
         * @param entries     更新内容
         */
        void update(Object entity, Where whereClause, UpdateEntry[] entries);

        /**
         * 执行删除
         *
         * @param entity      目标实体
         * @param whereClause 删除条件
         */
        void remove(Object entity, Where whereClause);

        /**
         * 持久化实体
         *
         * @param entities 要持久化的实体
         */
        void save(Object[] entities);

        /**
         * 开启事务
         */
        void txBegin();

        /**
         * 提交事务
         */
        void txCommit();

        /**
         * 回滚事务
         */
        void txRollback();

        /**
         * 销毁
         */
        void destroy();
}
